home *** CD-ROM | disk | FTP | other *** search
/ Alles Voor Internet / Tout Pour Internet / alles voor internet.iso / MacInternet™ / Telnet / Terminal 2.2 / Documentation / Terminal.doc < prev    next >
Text File  |  1992-01-17  |  60KB  |  1,475 lines
  1. ===========================================================================
  2. "Terminal"                 A Serial Communication Program For The Macintosh
  3. ===========================================================================
  4.  
  5.                         Version 2.0 (20-Nov-1990)
  6.  
  7.  
  8. ___________________________________________________________________________
  9. INTRODUCTION
  10.  
  11.  
  12. "Terminal" is a serial communication program for the Macintosh computer.
  13. Features are:
  14.  
  15. * Fast display. No characters are lost for up to 4800 Baud on a Mac Plus,
  16. or up to 9600 Baud on a Mac IIcx in 1-bit color mode, with text capture to
  17. disk enabled. (For most commercial programs this only holds for short term
  18. until the serial input buffer is full.)
  19.  
  20. * Capture buffer, so that the last 32768 (default, can be configured, upper
  21. limit is 32768 lines) characters are always available in the scrolling
  22. terminal window. The buffer can be saved as TEXT file to disk or appended
  23. to an existing file. Very fast scrolling to move around in the buffer.
  24.  
  25. * Text capture to disk, so that everything received or transmitted is saved
  26. automatically to a TEXT file on disk. Can also be appended to an existing
  27. file.
  28.  
  29. * Send TEXT files from disk, from up to 10 different macro buffers or from
  30. the clipboard. Wait for prompt string before sending line, delay after each
  31. line, delay after each character.
  32.  
  33. * XON/XOFF, CTS, DTR and CTS/DTR handshake. Hardware handshake is useful
  34. for high speed modems or terminal node controllers.
  35.  
  36. * Binary file transfer using X-Modem protocol (checksum, CRC or 1K
  37. options), Y-Modem (i.e. XModem batch), Z-Modem or CompuServe QuickB
  38. protocol (up- and download). Automatic recognition of MacBinary (I and II)
  39. file format.
  40.  
  41. * Built-in C interpreter with a rich set of intrinsic functions to execute
  42. scripts from TEXT files. Scripts can be as simple as modem setup, dial or
  43. auto-logon, but can also be used to program a complete BBS.
  44.  
  45. * Very compact program. Only about 90K on disk and can run in a 160K
  46. partition under MultiFinder.
  47.  
  48. * Complete non-modal user driven program (even during file transfers). Runs
  49. in the background under MultiFinder (even if "Set Aside" under
  50. MultiFinder). Several copies of the program may be run at the same time,
  51. under MultiFinder, each one on a different serial port.
  52.  
  53. * Recognizes and uses all serial devices that are correctly registered with
  54. the Communications Toolbox.
  55.  
  56. * The program is free.
  57.  
  58. * Source code is free (can be compiled with THINK C 4.02 or MPW 3.2 C).
  59.  
  60.  
  61. ___________________________________________________________________________
  62. CONFIGURATION
  63.  
  64.  
  65. "Terminal" was developed (in THINK C 4.02 and MPW 3.2) and tested on a
  66. Macintosh Plus and on a Macintosh IIcx with System 6.05 under MultiFinder
  67. 6.1b9 (The MultiFinder with the "Set Aside" option). The program is
  68. MultiFinder aware and can work in the background even if "Set Aside". HFS
  69. (hierarchical file system) and 128K ROMs (or newer) are required, so
  70. "Terminal" will not run on "old" Macs and needs at least a Mac Plus.
  71. "Terminal" was tested and runs fine with System 7.0b1 (October release).
  72.  
  73. I made no special attempts to stay compatible with old system versions, nor
  74. was the program tested on old system versions. But I made every effort to
  75. follow Apple's rules in order to stay compatible with future systems and
  76. hardware. (The only exception is the script function getdcd() where I had
  77. to read the status register of the SCC directly.)
  78.  
  79. "Terminal" will recognize all serial devices that are correctly registered
  80. with the Communications Toolbox, but otherwise does not use or require the
  81. Communications Toolbox.
  82.  
  83.  
  84. ___________________________________________________________________________
  85. FILES AND FOLDERS
  86.  
  87.  
  88. * "Terminal" the application, can be anywhere on your disk.
  89.  
  90. * "Terminal Folder" is a folder that should be created in the same folder
  91. as the "Terminal" application. All scripts (a script is a TEXT file with a
  92. suffix of ".s") in this folder will be included in the "Scripts" menu for
  93. easy execution. If this folder does not exist, all scripts in the same
  94. folder as the "Terminal" application will be included in the "Scripts"
  95. menu. This script folder, or the application folder if the script folder
  96. does not exist, is also used as the default folder for loading macro files
  97. by the script language (function "macrol"). If there is a file named
  98. "Macros.m" in this folder it will be loaded as the macro set at startup.
  99.  
  100. * "Terminal Settings" is created by "Terminal" in the "Terminal Folder", or
  101. in the application folder if "Terminal Folder" does not exist, to store the
  102. options selected. If this file is not found when "Terminal" starts up,
  103. default options will be used. In this file are also stored the current
  104. positions of the terminal and the progress window, so that they will be
  105. positioned again at the same location when the application is restarted.
  106. (The settings file is not stored in the System folder so that multiple
  107. copies of "Terminal" can run on the same machine, under MultiFinder, each
  108. one on a different port.)
  109.  
  110. * The "Terminal options" menu can be used to select a start-up script, that
  111. will be automatically executed when the application is started. This script
  112. can be anywhere on the disk. By default there is no start-up script. A
  113. script can force "Terminal" to quit when the script has finished. Using
  114. this feature and a startup script you can use Terminal to make file
  115. transfers from inside HyperCard stacks (you can even make HyperCard modify
  116. the startup script before running Terminal), or from other programmable
  117. applications that support launching other applications.
  118.  
  119. * Scripts can be started from the Finder by double-clicking (opening) if
  120. their creator was changed from the creator of the TEXT editor that created
  121. them to Terminal's creator. See the "Kiss script file" command in the
  122. "File" menu description.
  123.  
  124. * For use with Y-Modem batch, Z-Modem and CompuServe QuickB file transfers
  125. a folder must exist on the disk where all downloads and uploads using these
  126. protocols will look for and store files. This folder can be selected by
  127. using the "File transfer options" menu option. The default folder is the
  128. same as the folder containing the "Terminal" application. This folder is
  129. also the default folder used by script file commands.
  130.  
  131.  
  132. Note: If you had a previous version of "Terminal" on your disk please
  133. rebuild the Desktop file (hold down the option and the command key when
  134. booting) so that the Finder recognizes the new icons and file types.
  135.  
  136.  
  137. ___________________________________________________________________________
  138. THE TERMINAL WINDOW
  139.  
  140.  
  141. There is a fixed size window with 24 lines and 81 columns (default values,
  142. can be configured). The window can be moved anywhere on the screen. A
  143. vertical scroll bar allows fast moving around in the last 32768 (default
  144. value, can be configured) characters received. If a new character is
  145. received the text automatically scrolls to the end. Everything received is
  146. displayed in the terminal window, even if the window is not the frontmost
  147. or if the application was switched out under MultiFinder.
  148.  
  149. Note: "Terminal" tries to scroll the window as fast as possible. If the
  150. window is partially covered by other windows, the scrolling slows down some
  151. what. If during scrolling you move windows around, the terminal window
  152. might not update correctly. In this case simply click inside the terminal
  153. window to force "Terminal" to redraw the whole window.
  154.  
  155. The name of the window will be "Terminal" if no script is executing,
  156. otherwise the window name will be the same as the name of the script file.
  157. To cancel a running script select it again under the corresponding menu
  158. item.
  159.  
  160. If the terminal window is frontmost everything typed on the keyboard is
  161. transmitted. If the local-echo option is selected it is also echoed to the
  162. window. To send control characters the "Option" key (in this case all
  163. characters that are only available by using the "Option" key are no longer
  164. available) or the "Command" key (in this case the "Command" key cannot be
  165. used to select menu commands) can replace the "Control" key, if your
  166. keyboard doesn't have one.
  167.  
  168. After file transfers a statistics message is displayed in the top area of
  169. the window showing how much bytes were transferred in how much time. This
  170. area is also used to display error messages. If a message is displayed a
  171. button appears to the left of it. Clicking this button will erase the
  172. message and the button. Note that such a message is not a modal dialog but
  173. will stay as long as there is no new message or until it is cleared.
  174. Meanwhile the program continues its normal operation.
  175.  
  176. During file transfers a progress window (this is a non-modal window, not a
  177. modal dialog box, and can be moved around or deselected, and all menu
  178. commands are still available while this window is up) is displayed. This
  179. progress window shows the progress of the file transfer and has a "Cancel"
  180. button. By clicking in this "Cancel" button the file transfer can be
  181. aborted. The file transfer can also be canceled by selecting the
  182. corresponding menu item. If the progress window gets lost beneath other
  183. windows, use the "Edit" menu item "Show progress window".
  184.  
  185. Characters received in terminal mode are filtered using the following
  186. criteria (this is what I consider basic TTY emulation):
  187.  
  188. * All bytes received will get their most significant bit stripped to make 7
  189. bit ASCII characters.
  190.  
  191. * A "CR" character (carriage return, ASCII 13) will move the cursor to the
  192. first position in the next line.
  193.  
  194. * A "Backspace" character will erase the last character received and move
  195. the cursor one position to the left, but will never move to the previous
  196. line. The code to be recognized as "Backspace" can be chosen (see "Options
  197. menu"). If TEXT file capture is on, all characters are saved as received in
  198. the file including the "Backspace" characters.
  199.  
  200. * A "TAB" character (ASCII 9) will be accepted (and saved if TEXT file
  201. capture is on) but displayed as a space character.
  202.  
  203. * Five consecutive "CAN" (control-X, ASCII 24) are recognized as a signal
  204. to abort text file sends, X/Y-Modem or ZModem file transfers.
  205.  
  206. * A "BEL" (control-G, ASCII 7) is recognized and if this feature is enabled
  207. via the "Other options..." menu item, the Macintosh will beep. The "BEL"
  208. character is not saved to the terminal buffer or capture file.
  209.  
  210. * All other control characters are ignored and only characters with ASCII
  211. codes higher then 32 and lower than 126 are accepted (printable
  212. characters).
  213.  
  214. * If lines longer than 81 (depends on the configured window width)
  215. characters are received a "CR" will be inserted automatically after every
  216. 81 characters, and this "CR" will also be saved to disk if TEXT capture is
  217. on.
  218.  
  219.  
  220. ___________________________________________________________________________
  221. THE "FILE" MENU
  222.  
  223.  
  224. SAVE CAPTURE BUFFER
  225.  
  226. A standard file dialog is presented (if the capture buffer is not empty)
  227. allowing to save the contents of the capture buffer to disk as a TEXT file.
  228. The TEXT file creator can be changed using the "Text capture option" item
  229. in the "OPTIONS" menu. If a modifier key (shift, command or option) is
  230. pressed while selecting the menu option the capture buffer gets appended to
  231. the end of an existing TEXT file.
  232.  
  233.  
  234. TEXT CAPTURE
  235.  
  236. A standard file dialog is presented allowing to create the TEXT file where
  237. all further input or output will be saved. The TEXT file creator can be
  238. changed using the "Text capture option" item in the "OPTIONS" menu. The
  239. menu text will change to outlined and expanded, so that when selected again
  240. the capture file will be closed. The file is also automatically closed when
  241. quitting the program. If a modifier key (shift, command or option) is
  242. pressed while selecting the menu option the capture buffer gets appended to
  243. the end of an existing TEXT file.
  244.  
  245.  
  246. TEXT SEND
  247.  
  248. A standard file dialog is presented to select a TEXT file. The file
  249. contents is sent using the options that can be selected in the "TEXT file
  250. transfer options..." item of the "Options" menu. The menu text will change
  251. to outlined and expanded, so that when selected again the transmission will
  252. be canceled. If five control-X characters are received the transmission is
  253. also canceled.
  254.  
  255.  
  256. FILE RECEIVE
  257.  
  258. If X/Y-Modem is enabled and if Y-Modem batch is active, or if Z-Modem is
  259. enabled, the file transfer starts immediately. During such a session more
  260. than one file my be received. All files received are stored in the folder
  261. selected by the "Binary File Transfer Options" dialog. If MacBinary file
  262. format is enabled, the file name used will be the name from the MacBinary
  263. header if this name does not yet exist, otherwise the name from the Y-Modem
  264. header (block 0) or the Z-Modem file information block will be used, and if
  265. a file with this name exists it is deleted first. If MacBinary is disabled
  266. the file name from the Y-Modem header (block 0), or the Z-Modem file
  267. information block, is used, and if a file with this name exists it is
  268. deleted first.
  269.  
  270. Note: Z-Modem creates a temporary file while receiving. This file is not
  271. deleted when the Z-Modem transfer is aborted. Instead when the Z-Modem
  272. receive is resumed later on, it will continue were it stopped before. This
  273. partial Z-Modem file has a special file type and a distinct icon. Only when
  274. the receive is complete, will the file type changed to what it should be.
  275.  
  276. If X/Y-Modem without the batch option (i.e. X-Modem) is chosen a standard
  277. file dialog is presented to create a file to be used for binary file
  278. receive using X-Modem protocol. The X-Modem protocol file receive session
  279. is started. If MacBinary file format is enabled, the file name used will be
  280. the name from the MacBinary header if this name does not yet exist,
  281. otherwise the first chosen name will be used.
  282.  
  283. Note: For CompuServe QuickB protocol file transfers there is no need for
  284. this menu option as the transfers will be initiated by the host and the
  285. host will prompt you for the file name on your computer. For ZModem receive
  286. there is an option (that can be set in the Z-Modem options dialog) to
  287. automatically start the receive, so the FILE RECEIVE menu command need not
  288. be used.
  289.  
  290.  
  291. FILE TRANSMIT
  292.  
  293. A standard file dialog is presented to select the binary file to transmit
  294. using X/Y-Modem or Z-Modem protocol. If the MacBinary file format is
  295. enabled the file is sent in MacBinary II format. In Y-Modem batch, or
  296. Z-Modem, only one file can be send in a session.
  297.  
  298. Note: For CompuServe QuickB protocol file transfers there is no need for
  299. this menu option as the transfers will be initiated by the host and the
  300. host will prompt you for the file name on your computer.
  301.  
  302.  
  303. MAKE MACBINARY FILE
  304.  
  305. Use this utility option to create a MacBinary II file from any other file
  306. on your disk. The MacBinary file gets a special file type and a distinct
  307. icon. Normally this operation need not to be used, because the FILE
  308. TRANSMIT menu command will create the MacBinary II file on the fly while
  309. transmitting.
  310.  
  311.  
  312. EXTRACT FROM MACBINARY FILE
  313.  
  314. Use this utility option to extract a file from a MacBinary I or MacBinary
  315. II file on your disk. This is useful if you have forgotten to enable
  316. automatic MacBinary recognition and you have already downloaded a file.
  317.  
  318.  
  319. KISS SCRIPT FILE
  320.  
  321. Use this utility option to change the creator of TEXT files so that the
  322. "Finder" recognizes them as "Terminal" documents. In this way you can
  323. double-click the script file and it will automatically be executed by
  324. "Terminal". Only TEXT files with a file name ending in ".s" can be changed.
  325. To change back the creator of the TEXT file to the creator of the text
  326. editor application, hold down the option key while selecting the KISS
  327. SCRIPT FILE menu command. The creator of the TEXT file will be set to the
  328. TEXT file creator you have set in the OTHER OPTIONS dialog. When you now
  329. double-click the script file, the text editor will open it.
  330.  
  331.  
  332. QUIT
  333.  
  334. To quit and return to the "Finder" use this option or click in the close
  335. box of the terminal window.
  336.  
  337.  
  338. ___________________________________________________________________________
  339. THE "EDIT" MENU
  340.  
  341.  
  342. The first five items are there for desk accessories. Only the following is
  343. used:
  344.  
  345.  
  346. PASTE
  347.  
  348. The text in the clipboard is sent using the options that can be selected in
  349. the "TEXT file transfer options..." item of the "Options" menu. The menu
  350. text will change to outlined and expanded, so that when selected again the
  351. transmission will be canceled. If five control-X characters are received
  352. the transmission is also canceled.
  353.  
  354.  
  355. CLEAR CAPTURE BUFFER
  356.  
  357. This will clear the capture buffer and the terminal window.
  358.  
  359.  
  360. SHOW PROGRESS WINDOW
  361.  
  362. This selects the progress window and brings it to the front. Useful if the
  363. progress window gets covered by other windows.
  364.  
  365.  
  366. DEBLOCK SEND
  367.  
  368. This kills any outstanding serial write request. It might be useful if the
  369. program has received an XOFF, but never got the XON.
  370.  
  371.  
  372. NEGATE DTR
  373.  
  374. This negates the DTR output (output handshake signal).
  375.  
  376.  
  377. ASSERT DTR
  378.  
  379. This asserts the DTR output (output handshake signal).
  380.  
  381.  
  382. CHECK CTS
  383.  
  384. This displays the current status of the CTS input (input handshake signal)
  385. in the status message window.
  386.  
  387.  
  388. ___________________________________________________________________________
  389. THE "OPTIONS" MENU
  390.  
  391.  
  392. The options selected in the following dialogs are saved in a file, so that
  393. they are again available when the program is started at a later time (the
  394. file name is "Terminal Settings"). If no options file is found when the
  395. program is started, default values will be used.
  396.  
  397.  
  398. COMMUNICATION
  399.  
  400. * Port: None, "Modem", "Printer" or any other serial port available.
  401. * Baud rate: 300 to 56700 Baud.
  402. * Data bits: 7 or 8.
  403. * Stop bits: 1 or 2.
  404. * Parity: even, odd or none.
  405. * Handshake: XON/XOFF, CTS only, DTR only, CTS and DTR.
  406.  
  407. * Don't drop DTR when quitting: useful if you don't want the modem to
  408. hang-up when you quit the program.
  409.  
  410. Note: During X/Y-Modem or QuickB binary file transfers the data bits are
  411. set to 8 bits. When the transfer is finished the original value is
  412. restored. Z-Modem automatically will escape all characters that use the
  413. high order bit if 7 data bits are used thus enabling binary file transfers
  414. over non-transparent links.
  415.  
  416.  
  417. TEXT FILE SEND
  418.  
  419. * Wait for prompt before sending next line: If this option is checked the
  420. program will wait for the prompt string (this can be more than one
  421. character) before sending the next line while sending TEXT files.
  422.  
  423. * Delay after each line sent: If this option is checked the program waits
  424. for the specified number of ticks (1/60 second) before sending the next
  425. line while sending TEXT files.
  426.  
  427. * Delay after each character sent: If this option is checked the program
  428. waits the specified number of ticks (1/60 second) before sending the next
  429. character while sending TEXT files.
  430.  
  431. Note: the TEXT file send parameters are also used when sending macros or
  432. pasting text from the clipboard.
  433.  
  434.  
  435. TERMINAL
  436.  
  437. * Echo: local (display keyboard characters), remote (retransmit received
  438. characters).
  439.  
  440. * Display and capture: if checked the capture window and buffer are active,
  441. else nothing is displayed nor captured.
  442.  
  443. * AutoLF: If this option is checked a linefeed character will be send after
  444. each carriage return character.
  445.  
  446. * Start-up script: Any script can be selected to be executed automatically
  447. when the "Terminal" application is started.
  448.  
  449.  
  450. OTHER
  451.  
  452. * Text capture file creator: file creator for TEXT files used for saving
  453. the capture buffer or by the "Text file capture" option. So if you double-
  454. click on these files your favorite text editor program is automatically
  455. called. If you un-kiss (see FILE MENU) script files they will get this
  456. creator.
  457.  
  458. * File type and creator for non-MacBinary files: if automatic MacBinary
  459. file format recognition is not enabled, or if the file received is not a
  460. valid MacBinary file, this type (default is 'TEXT') and creator are used
  461. for the new file.
  462.  
  463. * Code for "backspace" key: ASCII code send by pressing the "Backspace"
  464. key, and also the ASCII code recognized as "Backspace" code while
  465. receiving.
  466.  
  467. * Code for "`" key: ASCII code send by pressing the "`" key. This can be
  468. used to make an "ESC" key (ASCII 27) on keyboards that don't have an "ESC"
  469. key.
  470.  
  471. * Control-G beeps: if checked any "BEL" (control-G, ASCII 7) character
  472. received will beep.
  473.  
  474. * Control key: the keyboard modifier key to be used for sending control
  475. characters (e.g. cntl-C). On keyboards lacking a "control" key, use either
  476. the "option" key (in this case you cannot send the characters that normally
  477. are only available by using the "option" key) or the "command" key (in this
  478. case you cannot execute menu commands by key equivalent).
  479.  
  480.  
  481. BINARY FILE TRANSFER
  482.  
  483. * MacBinary: use and recognize MacBinary file format in file transfers
  484. (Note that TEXT files are never sent as MacBinary).
  485.  
  486. * CIS-B: recognize and use CompuServe QuickB protocol for file transfers.
  487. If you don't use QuickB uncheck this option. This makes things faster and
  488. eliminates any false triggering into file transfer mode on noisy lines.
  489.  
  490. * X/Y-MODEM: use X-Modem or Y-Modem file transfers when using the
  491. "Receive..." or "Transmit..." commands from the FILE menu. Options can be
  492. set in the "XY-Modem Options..." dialog.
  493.  
  494. * Z-MODEM:  use Z-Modem file transfers when using the
  495. "Receive..." or "Transmit..." commands from the FILE menu. Options can be
  496. set in the "Z-Modem Options..." dialog.
  497.  
  498. * Auto-receive: when this is checked, Z-Modem receive will start
  499. automatically as soon as a the other side has started transmitting. If you
  500. rarely make Z-Modem file transfers, don't check this. This makes things
  501. faster. The likelihood of false triggering is small, but nevertheless
  502. exists.
  503.  
  504. * Path for up- and downloads: folder name used for CIS-B up- and downloads
  505. (because the host will only prompt for the file name on your computer but
  506. not the path name), for Y-Modem batch or Z-Modem file downloads (where only
  507. the file name is in the header block).
  508.  
  509.  
  510. XY-MODEM OPTIONS
  511.  
  512. * CRC        If not checked "classic" X-Modem with simple checksum and 128
  513.              Byte blocks will be used. The "1K" options are disabled.
  514.              If checked CRC error checking will be used and the "1K"
  515.              options are enabled.
  516. * 1K off     128 Byte blocks are used.
  517.      aut     128 or 1024 Byte blocks are used automatically and where
  518.              appropriate. During the initial handshaking phase the single
  519.              character "C" is used. This is the "official" way of doing it.
  520.      CK      1024 Byte blocks are used if during the initial handshaking
  521.              phase the two character sequence "CK" is used (this is used by
  522.              Red Ryder 10.3 and perhaps others).
  523. * batch off  No batch protocol is used, i.e. this is X-Modem.
  524.         Y    "Official" Y-Modem batch protocol is used.
  525.         RR   A variant of the Y-Modem batch protocol is used where there is
  526.              no new handshaking phase after the header block (block 0) has
  527.              been sent (this is used by Red Ryder 10.3 and perhaps others).
  528. * timeout    Select the value 5, 10, 15 or 20 seconds.
  529.  
  530.  
  531. Z-MODEM OPTIONS
  532.  
  533. The first three options are used for receive and transmit.
  534.  
  535. * Escape control characters: if this is checked all control characters are
  536. escaped (including all characters who have their high order bit set). This
  537. slows down Z-Modem but must be used on non-transparent links. In any case,
  538. if using 7 data bits, Z-Modem will ignore this setting and escape all
  539. control characters.
  540.  
  541. * Timeout (seconds): should be set at 10 seconds.
  542.  
  543. * Maximal retries: should be set at 10.
  544.  
  545. The following option is only for Z-Modem receive.
  546.  
  547. * Receive buffer size (bytes): can be set to 0 or a value between 128 and
  548. 32768. If set to 0 the receiver signals to the transmitter that it is able
  549. to receive and save data as fast as it is coming in. Otherwise the sender
  550. will make sure to never have more than this number of non-acknowledged
  551. bytes and waits while the receiver will save the data.
  552.  
  553. The following options are only used for Z-Modem transmit.
  554.  
  555. * Transmit sub-packet length (bytes): can be set to 256 for speeds up to
  556. 1200 Baud, 512 for speeds between 1200 and 2400 Baud, and to 1024 (maximum)
  557. for higher speeds as recommended in the Z-Modem specifications. The
  558. optimum value depends on the link quality. On good links, 1024 (maximum)
  559. should be used.
  560.  
  561. * Window limit (bytes): can be set to a value between 0 and 32768. If set
  562. to 0 now transmit window is used. Otherwise the sender makes sure to never
  563. have more than this number of non-acknowledged bytes.
  564.  
  565. * ZCRQ spacing (bytes): can be set to a value between 0 and 32768. If set
  566. to 0 the sender will not send ZCRQ frames. Otherwise it will send a ZCRQ
  567. frame after having send this number of bytes. ZCRQ frames are used to see
  568. how far the receiver has got, but will otherwise not interrupt the data
  569. stream.
  570.  
  571. You should consult the Z-Modem specifications to get more details about
  572. these parameters. The default values should be fine for most cases.
  573.  
  574.  
  575. ___________________________________________________________________________
  576. THE "MACROS" MENU
  577.  
  578.  
  579. A macro is a text string kept in memory. There are 10 macro string buffers
  580. available. There is a different menu item for each possible buffer. The
  581. menu item name is the macro name, not it's content. The only limit for the
  582. length of a macro string length is available memory. The command key
  583. equivalents are 0 to 9. When the menu item is selected, or when the
  584. corresponding command key is pressed, the macro string is send out through
  585. the serial port using the parameters that are normally used for sending
  586. text files (prompt string, line and character delays, handshake option). So
  587. macro strings behave like text files, but are kept in memory and can be
  588. send easily with single keystrokes. If you press the option or the shift
  589. key while selecting a macro, the macro string is not send out but simply
  590. displayed in the terminal window. This can be used to test macro sets.
  591.  
  592. The first menu item is used to load a new macros file using a standard get
  593. file dialog. A macros file is a simple TEXT file with a ".m" suffix, that
  594. contains a complete set of macros, up to 10 different macros. This text
  595. file can be created and edited with any TEXT editor. If there exists a file
  596. named "Macros.m" in the script folder it will be used automatically when
  597. the Terminal program is started. The contents of the macros file must
  598. respect the following rules:
  599.  
  600. * Macro names start with the two characters "\m" (or "\M") and continue
  601. until the end of the line. They will get truncated to 30 characters in the
  602. "Macros" menu.
  603.  
  604. * All the text following a macro name becomes the macro text, including any
  605. line returns, they are translated to carriage return characters. The macro
  606. text stops one character before (the last character, usually the final line
  607. return, is not included) the beginning of a new macro name, or at the end
  608. of the file. The only limit for the length of macro text is available
  609. memory.
  610.  
  611. * To include the backlash character in macro text use the two character
  612. sequence "\\". To include control characters, other than the carriage
  613. return which is the same as control-M, use the two character sequence "\x",
  614. where "x" is the control character to use. E.g. to include control-C use
  615. "\C" (or "\c").
  616.  
  617. * Macros found in the macros file will get numbered automatically starting
  618. at 0. Macro numbers not used will get disabled in the menu.
  619.  
  620. See the included examples of some macro files to see how they might look
  621. like.
  622.  
  623. Note: the macro files to be loaded by the script function "macrol" must be
  624. in the "Terminal folder".
  625.  
  626.  
  627. ___________________________________________________________________________
  628. THE "SCRIPTS" MENU
  629.  
  630.  
  631. A script is a TEXT file containing a program written in "Terminal" script
  632. language, which is a subset of the C language. Scripts are interpreted by
  633. "Terminal", there is no compilation step involved. The easiest way to
  634. maintain scripts is to use a desk accessory TEXT editor. If you use a word
  635. processor, you must save the script files as pure TEXT, not in the native
  636. format of the word processor.
  637.  
  638. The first item in this menu can be used to select any script file on your
  639. disk using a standard file dialog box. Only TEXT files with a suffix of
  640. ".s" are considered to be scripts.
  641.  
  642. The other items depend on what "Terminal" found in it's folder when it was
  643. started. If a folder "Terminal Folder" exists in the application folder,
  644. all script files found there are included in the menu. If no such folder
  645. exists all script files found in the application folder are listed in the
  646. menu. Selecting a script in the menu will start it. The menu item name
  647. changes to outlined and expanded. To cancel a running script simply select
  648. it's menu item again. If a script is running the terminal window's name is
  649. set to the name of the executing script.
  650.  
  651. Only one script at a time can be executing. Any script can be selected to
  652. execute automatically when "Terminal" is started by using the "Terminal
  653. Options" menu. You can also double-click script files from the Finder, if
  654. they have been "kissed" before (see FILE menu commands). They are
  655. automatically opened and executed by "Terminal".
  656.  
  657.  
  658. ___________________________________________________________________________
  659. THE SCRIPT LANGUAGE
  660.  
  661.  
  662. The script language interpreted by "Terminal" is a subset of C with many
  663. specialized intrinsic (built-in) functions. Please read a C reference book
  664. to learn the C syntax, or see the enclosed script examples to get a feeling
  665. of the language. I will not write a book about programming in C here, only
  666. tell you the essentials.
  667.  
  668.  
  669. PROGRAM
  670.  
  671. A program is recognized as a script if it is in a TEXT file, and if the
  672. file name ends in ".s". Spaces, tabs and carriage return characters are
  673. considered to be white space. No identifier and no keyword can be separated
  674. by white space. A program consists of: comments, global variable
  675. definitions and function definitions. Everything included between "/*" and
  676. "*/" is considered a comment and will not be interpreted. Comments cannot
  677. be nested. The "/*" and "*/" are not recognized as comment delimiters
  678. inside string or character constants. Global variables are those variables
  679. that are known to all functions, unless their names are reused as local
  680. variables. Global variables can be initialized using any expression that
  681. involves either constants or other globals that are already defined at that
  682. point. Function definitions can appear in any order and their must be at
  683. least one function called "main" with no parameters. It is this function
  684. that is called when the script is started. Every function is supposed to
  685. return an integer value as result. If there is no return statement in a
  686. function, 0 will be returned. Functions can be called recursively. There
  687. are many built-in functions that are already defined when the script is
  688. started.
  689.  
  690. The value the "main" function returns is used as follows:
  691.       0 : Don't restore saved settings, continue application
  692.       1 : Restore saved settings, continue application
  693.     256 : Don't restore saved settings, quit application
  694.     257 : Restore saved settings, quit application
  695. Restore saved settings means that all changes the script made to settings
  696. are forgotten as soon as the script finishes. Quit application means, that
  697. as soon as the script has finished, "Terminal" quits. Usually this means
  698. returning to the Finder. But if "Terminal" was launched from HyperCard it
  699. will return to HyperCard.
  700.  
  701. This is an example of a simple script that displays the message "The number
  702. is 123" in the terminal window:
  703.  
  704.     int Number = 123;   /* This is a global variable */
  705.  
  706.     main ()     /* Every script must have a main() function */
  707.     {
  708.         /* display() is a built-in function */
  709.         display("The number is %i\r", Number);
  710.     }
  711.  
  712.  
  713. IDENTIFIERS
  714.  
  715. An identifier is a sequence of letters and digits; the first character must
  716. be a letter. The underscore "_" counts as a letter. An identifier can be of
  717. any length up to 255 characters. All characters are significant and are
  718. case sensitive. There are three types of identifiers: keywords, function
  719. names, variable names. The keywords are: "break", "char", "else", "for",
  720. "if", "int", "return", "while".
  721.  
  722.  
  723. CONSTANTS
  724.  
  725. An integer constant is a sequence of decimal digits, or 0x followed by up
  726. to 8 hexadecimal digits. An integer value is represented internally by 4
  727. bytes (32 bits). A minus sign before a constant is considered as an unary
  728. operator, not a part of the constant itself. A character constant is a
  729. sequence of 1 to 4 characters enclosed in single quotes. Character
  730. constants are converted to integer values, the byte values corresponding to
  731. the ASCII codes of the characters. A string constant is a sequence of
  732. characters enclosed in double quotes. String constants are automatically
  733. terminated by a NULL character. The value of a string constant is the
  734. address of the first character. Some examples of valid constants:
  735.  
  736.     1234567
  737.     0xABCD1234
  738.     'a'
  739.     'TEXT'
  740.     "An apple a day keeps troubles away"
  741.  
  742. In character and string constants the backslash "\" is used as an escape
  743. sequence according to the following table:
  744.  
  745.     LF      0x0A    \n
  746.     TAB     0x09    \t
  747.     FF      0x0C    \f
  748.     BELL    0x07    \a
  749.     BS      0x08    \b
  750.     CR      0x0D    \r
  751.     VT      0x0B    \v
  752.     NULL    0x00    \0
  753.     any     0x..    \x..    (2 hex digits)
  754.  
  755. If the character following a backslash is not one of those specified the
  756. backslash is ignored. This can be used to represent the backslash itself,
  757. to put a single quote into a character constant or to put a double quote
  758. into a string constant. Some examples;
  759.  
  760.     "Going to the next line...\r"
  761.     '\0'
  762.     "This is a single backslash: \\"
  763.     "\"Hello world!\""
  764.     '\''
  765.     '\x03'  /* That's a control-C */
  766.  
  767.  
  768. VARIABLES
  769.  
  770. There are four types of variables: characters, integers, pointers and
  771. arrays. Integers represent 32 bit signed values and characters 8 bit signed
  772. values. Pointers hold the 32 bit address of integers, characters or other
  773. pointers. Arrays are more or less equivalent to pointers. The following
  774. examples show how variables are defined:
  775.  
  776.     char c;     /* "c" is a character variable */
  777.     int n;      /* "n" is an integer variable */
  778.     char *ptr;  /* "ptr" is a pointer to characters */
  779.     char **hdl; /* "hdl" is a pointer to character pointers */
  780.     int *p;     /* "p" is a pointer to integers */
  781.     int **q;    /* "q" is a pointer to integer pointers */
  782.     char a[80]; /* "a" points to an array of 80 characters (80 bytes) */
  783.     int b[10];  /* "b" points to an array of 10 integers (40 bytes) */
  784.     char *c[5]; /* "c" points to an array of 5 character pointers (20 b) */
  785.     int *d[5];  /* "d" points to an array of 5 integer pointers (20 b) */
  786.  
  787. Variable declarations can be grouped together like this:
  788.  
  789.     char c, *ptr, **hdl, a[80], *c[5];
  790.     int n, *p, **q, b[10], *d[5];
  791.  
  792. Variables can be initialized using any legal expression, not only
  793. constants. Arrays can only be initialized at the global level, i.e. outside
  794. of function definitions. Initialized arrays must not include their size
  795. between the square brackets, the size is calculated based on the
  796. initializing values.
  797.  
  798.     char c = 'x';
  799.     int n = -123;
  800.     int m = n * 10;     /* "m" is set to -1230 */
  801.     char message[] = "This is a character string";
  802.     char *messages[] =  /* Array of strings */
  803.         { "This is string #1", "Another string", "and so on..." };
  804.     int a[] = { 1, 2, 3, 4, 5 };    /* Array of 5 integers */
  805.  
  806. The are no logical variables. Everything that is not zero is considered to
  807. be true.
  808.  
  809.  
  810. EXPRESSIONS
  811.  
  812. The following is a list of the supported operators that build up an
  813. expression. The list is by increasing precedence. Normally operators group
  814. left to right unless otherwise noted below. Note that the assignment is an
  815. operator, that an expression may contain several assignments, and that an
  816. assignment returns a value. Logical and numerical operators can be freely
  817. mixed, everything not zero is considered to be true. The precedence level
  818. can be changed by using parentheses. The boolean operators will return 1 as
  819. true.
  820.  
  821.     Assignment                      =                       (right to left)
  822.  
  823.     Logical or                      ||
  824.  
  825.     Logical and                     &&
  826.  
  827.     Equal, not equal                ==  !=
  828.  
  829.     Relational operators            <   <=  >   >=
  830.  
  831.     Add, subtract                   +   -
  832.  
  833.     Multiply, divide, modulo        *   /   %
  834.  
  835.     Logical not, increment,
  836.     decrement, unary minus,
  837.     indirection, address of         !   ++  --  -   *   &   (right to left)
  838.  
  839.     Function call, array element    ()  []
  840.  
  841. The increment or decrement operators can be used before or after a
  842. variable. If the operator comes before the variable (preincrement,
  843. predecrement) the variable is incremented, or decremented, and then the
  844. variable's value is used in the expression evaluation. If the operator
  845. comes after the variable (postincrement, postdecrement) the current value
  846. of the variable is used in the expression evaluation, and then the variable
  847. is incremented, or decremented.
  848.  
  849. Array subscripts start with 0. There is no runtime check of array
  850. boundaries. An array subscript can be any valid expression. Some examples:
  851.  
  852.     char a[80];
  853.     c = a[0];                       /* The first element */
  854.     c = a[79];                      /* The last element */
  855.     c = a[i = (79 - Func(x)*3)];    /* Expression as subscript */
  856.  
  857. For pointer arithmetic the following rules apply: if an integer value is
  858. added or subtracted from a pointer (a pointer is an address) then the
  859. integer value is first scaled depending on what the pointer is pointing to:
  860. 1 for characters, 4 for integers, 4 for pointers. If two pointers are
  861. subtracted the result is scaled in the same way and yields an integer value
  862. representing the number of objects separated by the two pointers. The two
  863. pointers must point to the same type of objects.
  864.  
  865. A function identifier without a parameter list in an expression results in
  866. the address of the function being used. If there is a parameter list, the
  867. function is called and the integer value returned by the function is used.
  868. Functions can also be called indirectly, using any expression that yields a
  869. valid function address followed by a parameter list. Some examples:
  870.  
  871.     int pf;         /* "int" can be used as function pointer */
  872.     int i;
  873.     pf = Func;      /* "pf" will contain address of function "Func" */
  874.     i = Func();     /* "i" gets function result */
  875.     i = (pf)();     /* "i" gets function result */
  876.  
  877.  
  878. FUNCTIONS
  879.  
  880. A function definition can only occur in the outer, global level. A function
  881. cannot be defined inside another function. All functions are supposed to
  882. return integers. A function definition consists of the function name,
  883. followed by a parameter definition list enclosed in parentheses, followed
  884. by a compound statement. The parameter definition list describes the
  885. function parameters. These parameters are considered as local variables
  886. inside the function. Example:
  887.  
  888.     /* The following function takes 3 parameters: a character, an integer
  889.     and a character pointer. It always returns the value 123. */
  890.  
  891.     Function (char c, int i, char *p)
  892.     {
  893.         /* ... */
  894.         return 123;
  895.     }
  896.  
  897. A function call consists of the function name followed by a parameter list.
  898. The parameter list is a comma separated list enclosed in parentheses of
  899. expressions. All parameters are passed by value. There is no verification
  900. if the number of parameters is correct or if the values passed to a
  901. function correspond to the types of the declared parameters. Example:
  902.  
  903.     i = Function ('x', 4567 + x, "Hello");
  904.  
  905.  
  906. STATEMENTS
  907.  
  908. A compound statement starts with an open brace "{" and terminates with a
  909. closing brace "}". There is an optional variable definition part followed
  910. by a list of statements. Variables defined inside a compound statement are
  911. local to that compound statement (block).
  912.  
  913. A statement can be:
  914.     compound statement
  915.     expression ;
  916.     if ( expression ) statement
  917.     if ( expression ) statement else statement
  918.     while ( expression ) statement
  919.     for ( opt expr1 ; opt expr2 ; opt expr3 ) statement
  920.     break ;
  921.     return ;
  922.     return expression ;
  923.     ;
  924.  
  925. The two forms of the conditional statement are:
  926.     if ( expression ) statement
  927.     if ( expression ) statement else statement
  928. In both cases the expression is evaluated and if it is nonzero, the first
  929. substatement is executed. In the second case the second substatement is
  930. executed if the expression is 0. The "else" ambiguity is resolved by
  931. connected an "else" with the last encountered "else"-less "if".
  932.  
  933. The "while" statement has the form:
  934.     while ( expression ) statement
  935. The substatement is executed repeatedly so long as the value of the
  936. expression remains nonzero. The test takes place before each execution of
  937. the statement.
  938.  
  939. The "for" statement has the form:
  940.     for ( opt expr1 ; opt expr2 ; opt expr3 ) statement
  941. This statement is equivalent to:
  942.     expression1 ;
  943.     while ( expression2 ) {
  944.         statement
  945.         expression3;
  946.     }
  947. Thus the first expression specifies initialization for the loop, the second
  948. specifies a test, made before each iteration, such that the loop is exited
  949. when the expression becomes 0; the third expression often specifies an
  950. incrementation which is performed after each iteration. Any or all of the
  951. expressions may be dropped. A missing expression2 makes the implied "while"
  952. clause equivalent to while(1); other missing expressions are simply dropped
  953. from the expansion above.
  954.  
  955. The statement
  956.     break ;
  957. causes termination of the smallest enclosing "while" or "for" statement;
  958. control passes to the statement following the terminating statement.
  959.  
  960. A function returns to its caller by means of the "return" statement, which
  961. has one of the forms:
  962.     return ;
  963.     return expression ;
  964. In the first case the returned value is undefined. In the second case the
  965. value of the expression is returned to the caller of the function. If
  966. required, the expression is converted to an integer. Flowing off the end of
  967. a function is equivalent to a return with no return value.
  968.  
  969. The null statement has the form
  970.     ;
  971. A null statement is useful to supply a null body to a looping statement
  972. such as "while".
  973.  
  974. Note: Unlike real C, logical expressions are completely evaluated, even if
  975. their TRUEthness (different from 0) ore FALSEness (equal to 0) can be
  976. determined before the whole expression is evaluated. In real C that's
  977. called short circuit boolean evaluation. For example in the statement
  978.     if (dothis() && dothat())
  979.         ;
  980. the functions dothis() and dothat() are always called in script C. In real
  981. C the function dothat() is only called if dothis() returns a non-zero
  982. result.
  983.  
  984.  
  985. ___________________________________________________________________________
  986. INTRINSIC FUNCTIONS
  987.  
  988.  
  989. Intrinsic functions are built-in and need not to be defined in the script.
  990. They can be called by any script.
  991.  
  992. All file access functions operate on the file transfer up- and download
  993. folder, which is the folder that can be set with the "Binary file transfer
  994. options..." menu item. File names can be up to 31 characters long and
  995. cannot contain the character ':'.
  996.  
  997. All formatting functions ("display", "format", "type") use a template
  998. string to specify the formatting to be done on the following parameters.
  999. Format specifiers begin with the character % and include zero or more of
  1000. the following conversion specification elements (optional fields are in
  1001. brackets):
  1002.  
  1003.     % [option flags] [field size] conversion
  1004.  
  1005. Some of these elements are optional, but if present, they must be specified
  1006. in the order in which they are described below.
  1007. Option flags (optional):
  1008.     -   Left adjust output in field, pad on right (default is to right
  1009.         justify).
  1010.     0   Use zero (0) rather than space for the pad character
  1011. Field size specification (optional):
  1012.     The minimum field width, expressed as a decimal integer. The
  1013.     corresponding parameter will be printed in a field at least this wide.
  1014. Conversion characters (required)
  1015.     c   Parameter is a character
  1016.     i   Parameter is an integer
  1017.     s   Parameter is a null terminated string
  1018.     %   Print a %, no parameter used
  1019. The format specification elements must correspond to the following
  1020. parameters. Some examples:
  1021.     char k, m[80];
  1022.     int n;
  1023.     type("Unrecognized character %c on line %i of file %s\r", k, n, m);
  1024.  
  1025. The following list describes all the existing intrinsic functions. They are
  1026. described in the so-called prototype format, i.e. the format you would have
  1027. to use to define them. E.g.
  1028.     xxxx (char *s, int i)
  1029. means that "xxxx" is a function taking 2 arguments, the first is a pointer
  1030. to a character and the second is an integer. Note that all functions return
  1031. integers, but the value returned is not necessarily meaningful for very
  1032. function.
  1033.  
  1034.  
  1035. autolf      Set the auto linefeed flag on or off
  1036.  
  1037.             autolf (int flg)
  1038.     flg:    0 means off, 1 means on
  1039.  
  1040.  
  1041. beep        Macintosh system beep
  1042.  
  1043.             beep ()
  1044.  
  1045.  
  1046. capture     Start/stop capture to text file
  1047.  
  1048.             capture (int opt, char *name)
  1049.     result: Macintosh file system error, 0 if no error
  1050.     opt:    0 = Close capture file
  1051.             1 = Capture on, new file
  1052.             2 = Capture on, append to existing file
  1053.     name:   Pointer to character string of at least 32 characters. This
  1054.             is the file name.
  1055.  
  1056.  
  1057. catalog     Return file info
  1058.  
  1059.             catalog (int i, char *name, int *type, int *dsize, int *rsize,
  1060.                 int *cdate, int *mdate)
  1061.     result: Macintosh file system error, 0 if no error
  1062.     i:      If 0, then name must be specified and information about the
  1063.             file with that name is returned, if it exists.
  1064.             If non-zero information (including file name) about the i-th
  1065.             file in the folder is returned.
  1066.     name:   Pointer to character string of at least 32 characters. This
  1067.             is the file name (specified or returned depending on the value
  1068.             of i).
  1069.     type:   Integer (4 bytes). File type.
  1070.     dsize:  Data fork size in bytes.
  1071.     rsize:  Resource fork size in bytes.
  1072.     cdate:  Creation date in seconds.
  1073.     mdate:  Modification date in seconds.
  1074.  
  1075.  
  1076. date        Convert seconds from Macintosh clock to date and time
  1077.  
  1078.             date (int sec, int *yr, int *mo, int *da, int *ho, int *mi,
  1079.                 int *se, int *dw)
  1080.     sec:    Seconds
  1081.     yr:     Year (1904..20xx)
  1082.     mo:     Month (1..12)
  1083.     da:     Day (1..31)
  1084.     ho:     Hour (0..23)
  1085.     mi:     Minutes (0..59)
  1086.     se:     Seconds (0..59)
  1087.     dw:     Day of week (1..7, Sunday is 1)
  1088.  
  1089.  
  1090. display     Display in the terminal window
  1091.  
  1092.             display (char *templ, ...)
  1093.     templ:  Template string
  1094.     ...:    Variable number of arguments (maximum 9)
  1095.  
  1096.  
  1097. download    Download (receive) a binary file using X/Y/Z-Modem protocol
  1098.  
  1099.             download (char *name, int bin, int zmodem)
  1100.     result: Error code. 0 if Ok. 1 if timeout. 2 if cancel. 3 if abort (5
  1101.             consecutive control-X characters received). All other values
  1102.             are Macintosh file system errors.
  1103.     name:   File name for new file (not used for Y-Modem batch or Z-Modem)
  1104.     bin:    1 to recognize and use MacBinary format
  1105.     zmodem: 0 use X/Y-Modem, 1 use Z-Modem
  1106.  
  1107.  
  1108. format      Formatted conversion of values into a string
  1109.  
  1110.             format (char *str, char *templ, ...)
  1111.     str:    String for result
  1112.     templ:  Template string
  1113.     ...:    Variable number of arguments (maximum 8)
  1114.  
  1115.  
  1116. free        Dispose of the memory allocated by the new() function
  1117.  
  1118.             free (char *p)
  1119.     p:      Pointer returned by previous call to new() function
  1120.  
  1121.  
  1122. getcts      Get current state of CTS input line
  1123.  
  1124.             getcts ()
  1125.     result: 0 if negated, 1 if asserted
  1126.  
  1127.  
  1128. getdcd      Get current state of DCD input line
  1129.  
  1130.             getdcd ()
  1131.     result: 0 if negated, 1 if asserted
  1132.  
  1133.  
  1134. lecho       Set the local echo flag on or off
  1135.  
  1136.             lecho (int flg)
  1137.     flg:    0 means off, 1 means on
  1138.  
  1139.  
  1140. macrol      Load new macros file
  1141.  
  1142.             macrol (char *name)
  1143.     result: Error code, 0 means no error
  1144.     name:   File name of TEXT file with macros (folder will be the same as
  1145.             the "Terminal folder")
  1146.  
  1147.  
  1148. macrox      Execute macro
  1149.  
  1150.             macrox (int i, int op, char *name)
  1151.     result: Error code, 0 ok, 2 cancel, 3 abort (2 consecutive control-X
  1152.             characters received)
  1153.     i:      Macro number (0 to 9)
  1154.     op:     0 send macro text (using send TEXT file parameters), 1 display
  1155.             macro text, 2 return macro name
  1156.     name:   Only used if op is 2, should point to a string where macro
  1157.             name will be returned (at least 30 characters long)
  1158.  
  1159.  
  1160. move        Move bytes from source to destination
  1161.  
  1162.             move (char *src, char *dest, int cnt)
  1163.     src:    Source pointer
  1164.     dest:   destination pointer
  1165.     cnt:    number of bytes to move
  1166.  
  1167.  
  1168. new         Allocate memory
  1169.  
  1170.             new (int size)
  1171.     result: Pointer to memory, or 0 if not enough memory available
  1172.     size:   Number of bytes to allocate
  1173.  
  1174.  
  1175. nextbuff    Wait for some characters
  1176.  
  1177.             nextbuff (char *buff, int count, int t)
  1178.     result: count characters received, 1 timeout, 2 cancel, 3 abort
  1179.             (5 consecutive control-X characters received)
  1180.     count:  Number of characters to wait for
  1181.     buff:   Character buffer to hold received characters. Must be at least
  1182.             count characters long
  1183.     t:      Timeout value in ticks (1/60th of second)
  1184.  
  1185.  
  1186. nextline    Wait for the next line received over the serial input port
  1187.  
  1188.             nextline (char *line, int t)
  1189.     result: 0 line received, 1 timeout, 2 cancel, 3 abort (5 consecutive
  1190.             control-X characters received)
  1191.     line:   String to hold line, this will be a '\0' terminated string
  1192.             without the final carriage return
  1193.     t:      Timeout value in ticks (1/60th of second)
  1194.  
  1195.  
  1196. pause       Pause for specified amount of time
  1197.  
  1198.             pause (int t)
  1199.     result: 1 timeout, 2 cancel.
  1200.     t:      Timeout value in ticks (1/60th of second)
  1201.  
  1202.  
  1203. prompt      Wait for a prompt string to come over the serial input port
  1204.  
  1205.             prompt (char *str, int t)
  1206.     err:    0 string received, 1 timeout, 2 cancel, 3 abort (5 consecutive
  1207.             control-X characters received).
  1208.     str:    String to wait for (case sensitive)
  1209.     t:      Timeout value in ticks (1/60th of second)
  1210.  
  1211.  
  1212. protocol    Set binary file transfer options
  1213.  
  1214.             protocol (bin, qb, zmodem, autorx)
  1215.     bin:    0 no MacBinary, 1 use MacBinary, -1 no change
  1216.     qb:     0 no QuickB, 1 use QuickB, -1 no change
  1217.     zmodem: 0 Z/Y-Modem, 1 Z-Modem, -1 no change
  1218.     autorx: 0 no auto-receive, 1 Z-Modem auto-receive, -1 no change
  1219.  
  1220.  
  1221. recho       Set the remote echo flag on or off
  1222.  
  1223.             recho (int flg)
  1224.     flg:    0 means off, 1 means on
  1225.  
  1226.  
  1227. save        Set the save & display flag on or off
  1228.  
  1229.             save (int flg)
  1230.     flg:    0 means off, 1 means on
  1231.  
  1232.  
  1233. send        Send a text file over the serial output port
  1234.  
  1235.             send (char *name)
  1236.     result: error code. 0 if Ok. 2 if cancel. 3 abort (5 consecutive
  1237.             control-X characters received). All other values are Macintosh
  1238.             file system errors.
  1239.     name:   File name
  1240.  
  1241.  
  1242. setdtr      Set DTR output line
  1243.  
  1244.             setdtr (int onoff)
  1245.     onoff:  0 to negate, 1 to assert
  1246.  
  1247.  
  1248. setup       Serial communications port setup
  1249.  
  1250.             setup (int baud, int data, int parity, int stop, char *port,
  1251.                 int dtr, int hs)
  1252.     result: 0 if no error
  1253.     baud:   0=300, 1=600, 2=1200, 3=2400, 4=4800, 5=9600, 6=19200, 7=38400,
  1254.             8=57600 baud (or -1 for no change)
  1255.     data:   0=7, 1=8 data bits (or -1 for no change)
  1256.     parity: 0=no, 1=even, 2=odd parity (or -1 for no change)
  1257.     stop:   0=1, 1=2 stop bit (or -1 for no change)
  1258.     port:   port's name, e.g. "Modem Port" or "Printer Port"
  1259.             (or -1 for no change)
  1260.     dtr:    1=don't drop DTR when quitting (or -1 for no change)
  1261.     hs:     Handshake 0=none, 1=XON/XOFF, 2=CTS, 3=DTR, 4=CTS/DTR
  1262.  
  1263.  
  1264. stack       Return free memory available for script heap and stack
  1265.  
  1266.             stack ()
  1267.     result: Combined free heap and stack space (bytes)
  1268.  
  1269.  
  1270. strcmp      Compare two strings (not case sensitive)
  1271.  
  1272.             strcmp (char *str1, char *str2)
  1273.     result: 0 if strings are equal, positive if str1 > str2, negative if
  1274.             str1 < str2
  1275.     str1:   First string
  1276.     str2:   Second string
  1277.  
  1278.  
  1279. terminal    Set terminal parameters
  1280.  
  1281.             terminal (int lecho, int recho, int autolf, int save)
  1282.     lecho:  Local echo flag (or -1 if no modification)
  1283.     recho:  Remote echo flag (or -1 if no modification)
  1284.     autolf: Auto line feed flag (or -1 if no modification)
  1285.     save:   Save & capture flag (or -1 if no modification)
  1286.  
  1287.  
  1288. text        Set text file send parameters
  1289.  
  1290.             text (char *prompt, int lined, int chard)
  1291.     prompt: Prompt text
  1292.     lined:  Ticks to wait after each line
  1293.     chard:  Ticks to wait after each character
  1294.  
  1295.  
  1296. time        Return seconds from Macintosh clock
  1297.  
  1298.             time ()
  1299.     result: Seconds
  1300.  
  1301.  
  1302. type        Send a string over the serial output port
  1303.  
  1304.             type (char *templ, ...)
  1305.     templ:  Template string
  1306.     ...:    Variable number of arguments (maximum 9)
  1307.  
  1308.  
  1309. upload      Upload (transmit) a binary file using X/Y/Z-Modem protocol
  1310.  
  1311.             upload (char *name, int bin, int zmodem)
  1312.     result: error code. 0 if Ok. 1 if timeout. 2 if cancel. 3 abort (5
  1313.             consecutive control-X characters received). All other values
  1314.             are Macintosh file system errors.
  1315.     name:   File name
  1316.     bin:    1 to recognize and use MacBinary format
  1317.     zmodem: 0 use X/Y-Modem, 1 use Z-Modem
  1318.  
  1319.  
  1320. val         Convert string to number
  1321.  
  1322.             val (char *str)
  1323.     result: Converted integer value
  1324.     str:    Character string (0 terminated)
  1325.  
  1326.  
  1327. xyparms     Set binary file transfer options for X/Y-Modem
  1328.  
  1329.             xyparms (crc, k, batch, t)
  1330.     crc:    0 use checksum, 1 use CRC, -1 no change
  1331.     k:      0 use 128 Byte blocks, 1 use 1 KByte blocks "C",
  1332.             2 use 1 KByte blocks "CK", -1 no change
  1333.     batch:  0 no batch (X-Modem), 1 batch official (Y-Modem),
  1334.             2 batch RR (Y Modem), -1 no change
  1335.     t:      timeout to use in ticks, -1 no change
  1336.  
  1337.  
  1338. zparms      Set binary file transfer options for Z-Modem
  1339.  
  1340.             zparms (ctl, t, retr, buf, pack, wind, crcq)
  1341.     ctl:    0 don't escape control characters, 1 escape control characters,
  1342.             -1 no change
  1343.     t:      timeout to use in ticks, -1 no change
  1344.     retr:   maximal retry count, -1 no change
  1345.     buf:    receive buffer size in bytes, -1 no change
  1346.     pack:   transmit sub-packet length in bytes, -1 no change
  1347.     wind:   transmit window size in bytes, -1 no change
  1348.     crcq:   transmit ZCRCQ spacing in bytes, -1 no change
  1349.  
  1350.  
  1351. ___________________________________________________________________________
  1352. THE CONFIGURATION RESOURCE
  1353.  
  1354.  
  1355. Some program parameters are kept in a configuration resource in the
  1356. "Terminal" application. These parameters cannot be changed while the
  1357. program is running, so there is no corresponding dialog in the "Options"
  1358. menu. You must use "ResEdit" to change those parameters. "Terminal"
  1359. includes the 'TMPL' (template resource) that "ResEdit" automatically will
  1360. use to edit the configuration resource. All numbers are entered as decimal
  1361. values. Buffer sizes are long integer values, i.e. maximum is 2147483647
  1362. bytes. The resource type is 'CNFG' and the id is 128.
  1363.  
  1364.  
  1365. Label                       Default     Description
  1366.  
  1367. Reserved                    0
  1368. Font size                   9
  1369. Lines                       24          Lines in terminal window
  1370. Columns                     81          Columns in terminal window
  1371. Terminal buffer size        32768       Size of terminal buffer (bytes)
  1372. Serial input buffer size    4096        Size of serial input buffer (bytes)
  1373. Reserved                    0
  1374. Script memory size          16384       Size of script memory (bytes)
  1375. Font name                   Monaco      Should be a monospaced font
  1376.  
  1377.  
  1378. On a 9" screen Monaco 9 with 24 lines of 81 columns fills the entire
  1379. screen. On a 13" screen Monaco 12 with 25 lines of 81 columns fills the
  1380. entire screen.
  1381.  
  1382. The terminal buffer can be greater than 32768 bytes, the only limitation is
  1383. 32768 lines of text in the buffer, because of the way the vertical scroll
  1384. bars is used in the terminal window. There is no practical limit for the
  1385. other buffers, other than available memory.
  1386.  
  1387. Note: if the buffer sizes are changed, the "SIZE" resource must be changed
  1388. accordingly under MultiFinder, otherwise the program may not get enough
  1389. memory. You can use the "About..." menu item to check for available memory
  1390. while "Terminal" is running. There should be at least 32768 bytes free.
  1391. With the original buffer sizes given "Terminal" runs fine in a 160K
  1392. partition.
  1393.  
  1394.  
  1395. ___________________________________________________________________________
  1396. HARDWARE
  1397.  
  1398.  
  1399. Signal assignments for the mini 8-pin serial port connectors (from "Guide
  1400. to Macintosh Family Hardware"):
  1401.  
  1402. Pin     Signal name     Signal description
  1403.  
  1404. 1       HSKo            Handshake output. Driven inverted from SCC's /DTR.
  1405.                         (That's what "Terminal" uses as DTR output)
  1406. 2       HSKi            Handshake input or external clock. Received
  1407.                         uninverted at SCC's /CTS and /TRxC. (That's what
  1408.                         "Terminal" uses as CTS input).
  1409. 3       TxD-            Transmit data (inverted). Driven inverted from
  1410.                         SCC's TxD; tri-stated when SCC's /RTS is not
  1411.                         asserted.
  1412. 4       GND             Signal ground. Connected to logic and chassis
  1413.                         ground.
  1414. 5       RxD-            Receive data (inverted); received inverted at
  1415.                         SCC's RxD.
  1416. 6       TxD+            Transmit Data. Driven uninverted from SCC's TxD;
  1417.                         tri-stated when SCC's /RTS is not asserted.
  1418. 7       GPi             General-purpose input (not connected on the Mac
  1419.                         Plus). Received inverted at SCC's DCD. (That's
  1420.                         what "Terminal" uses as DCD input).
  1421. 8       RxD+            Receive data. Received uninverted at SCC's RxD.
  1422.  
  1423.  
  1424. I have connected my modem (Abaton InterFax 24/96) with the following cable
  1425. (this should be suitable for all high speed modems using hardware
  1426. handshake):
  1427.  
  1428. Mac mini 8-pin      Modem 25-pin
  1429. 1 (HSKo)        --> 4 (RTS) and 20 (DTR)
  1430. 2 (HSKi)        <-- 5 (CTS)
  1431. 3 (TXD-)        --> 2 (TD)
  1432. 4 (GND)             7 (Common)
  1433. 5 (RxD-)        <-- 3 (RD)
  1434. 6 (TXD+)
  1435. 7 (GPi)
  1436. 8 (RxD+)            7 (Common)
  1437.  
  1438. I have connected my Terminal Node Controller (Kantronics KAM) for packet
  1439. radio with the following cable (hardware handshake in both directions):
  1440.  
  1441. Mac mini 8-pin      TNC 25-pin
  1442. 1 (HSKo)        --> 4 (RTS)
  1443. 2 (HSKi)        <-- 5 (CTS)
  1444. 3 (TXD-)        --> 2 (TD)
  1445. 4 (GND)             7 (Common)
  1446. 5 (RxD-)        <-- 3 (RD)
  1447. 6 (TXD+)
  1448. 7 (GPi)
  1449. 8 (RxD+)
  1450.  
  1451. To interconnect 2 Macintoshes, or to connect the modem port to the printer
  1452. port on the same Macintosh, I use an ImageWriter II cable.
  1453.  
  1454.  
  1455. ___________________________________________________________________________
  1456. COMMENTS AND SUGGESTIONS
  1457.  
  1458.  
  1459. Send any comments, bug reports and suggestions to my address:
  1460.  
  1461.     Erny Tontlinger
  1462.     33, route d'Arlon
  1463.     L-8410 Steinfort
  1464.     Luxembourg
  1465.  
  1466. or via electronic mail to my CompuServe account [73720,2200] (this can also
  1467. be done via Internet using the address 73720.2200@compuserve.com). I'm a
  1468. radio amateur, so you can reach me via the amateur packet radio network at
  1469. LX1YZ @ LX0PAC or via TCP/IP as [44.161.1.1] lx1yz.ampr.org.
  1470.  
  1471. This program is absolutely free, including the C sources. So do with it
  1472. what you like, but please include the documentation if you give it away. If
  1473. you use the program I would be happy to hear from you.
  1474. ___________________________________________________________________________
  1475.